/*
 * To change this template, choose Tools | Templates
 * and open the template in the editor.
 */
package bgu.ppm.sim.api;

import bgu.ppm.sim.api.env.Environment;
import bgu.ppm.sim.api.stat.StatisticsDatabase;

/**
 * a simulator is an object containing an environment (a collection of entities)
 * and a multi agent systems generators chain.
 *
 * the idea is that the simulator go over the chain and generate the MAS one
 * after the other. for each generated MAS the simulator than executes the MAS
 * in a tick based manner as defined in the MAS Execution Mode
 *
 * during the simulation the simulator post its progress into the
 * SimulationMonitor that it returns from the simulate function.
 *
 * the simulator provides services for the execution of the execution plan. for
 * example it provides the statistic database.
 *
 * @author User
 */
public interface Simulator {

    /**
     * @return the environment which is the group of entities that their
     * properties modified by the simulation.
     */
    Environment getEnvironment();

    /**
     * @return an opened (connected) database to store statistics record into.
     */
    StatisticsDatabase getStatisticsDatabase();


    /**
     * starts the simulation according to the MAS plan
     *
     * @return an incremental simulation result for the simulation. the result
     * will be updated as the simulation is running, before any other simulation
     * the old result must be closed in order the free important resources (like
     * database, event handlers, etc.)
     */
    IncrementalSimulationResult simulate();
}
